home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / batchut / tbu11.zip / TBU11.DOC < prev   
Text File  |  1989-03-26  |  11KB  |  233 lines
  1.  
  2. tBU v1.1 - Batch Utility - Planet Terus
  3.  
  4. [ Lines beginning with  (*) are those added by a fan of
  5.   the program who thought the docs needed a bit of improvement ]
  6.  
  7. Usage:    tbu <option symbol arg1 arg2 ...> <option ... >
  8.  
  9. Sets the DOS environment symbol based on the option chosen.  tBU will
  10. process multiple sets of option-symbol-arg sets from left to right.
  11.  
  12. (*) The program's author has used the word "symbol" to mean what most 
  13. (*) people call a "variable" - as in: "environment symbol" means
  14. (*) "environment variable."
  15.  
  16. Symbols may be used in batch commands as %SYMBOL% (symbol must appear
  17. in all capital letters). The symbol set by tBU CAN be empty. To check
  18. for an empty symbol use something like:
  19.     IF (%SYMBOL%) == () echo It's empty
  20.     IF not (%SYMBOL%) == () echo It's not empty
  21.  
  22. ERRORLEVEL is returned as 255 if error occured. The option character
  23. may be either a dash (-) or a slash (/).
  24.  
  25. (*) I have not found that the environment variables need to be
  26. (*) typed in all caps. Not with DOS 3.1, anyway.
  27.  
  28. (*) I have found that the program will fail consistently if you type
  29. (*) the command-line switches, such as "-f" or whatever, in CAPS.
  30. (*) Maybe that won't happen to everyone, but I must always type them
  31. (*) in lower case to get them to work!
  32.  
  33. Options:
  34.   -f  Parse filename & extension.      <sym> <filespec>
  35.       Sets symbol to the filename portion of arg1. Any dot name/
  36.       extension separator is not changed.
  37.       ERRORLEVEL:  Length of resulting string.
  38.       Example:  tbu -f file c:\tbu.exe  sets file to tbu.exe
  39.                 tbu -f file c:\data.    sets file to data.
  40.                 tbu -f file c:\data     sets file to data
  41.  
  42.   -x  Parse file extension only.       <sym> <filespec>
  43.       Sets symbol to the extension portion of arg1. The dot name/
  44.       extension separator is always removed.
  45.       ERRORLEVEL:  Length of resulting string.
  46.       Example:  tbu -e ext c:\cmd\tbu.exe  sets ext to exe
  47.  
  48. (*) The "." from the file name is NOT preserved in an environment
  49. (*) variable created with the "-x" switch.
  50.  
  51.   -n  Parse name only.                 <sym> <filespec>
  52.       Sets symbol to the name portion of arg1. The dot name/
  53.       extension separator is always removed.
  54.       ERRORLEVEL:  Length of resulting string.
  55.       Example:  tbu -n name c:\tbu.exe  sets name to tbu
  56.  
  57. (*) The "." from the file name is NOT preserved in an environment
  58. (*) variable created with the "-n" switch.
  59.  
  60. (*) Here is an instance in which you can stack commands on one
  61. (*) line. Let's say your %1 parameter for a batch file is a file
  62. (*) name, complete with extension. You could get the primary name
  63. (*) and the extension into two different variables in two different
  64. (*) passes, like this:
  65. (*)                      tbu -n name %1
  66. (*)                      tbu -x ext %1
  67.  
  68. (*) But why not do it in one pass? Like this:
  69. (*)          tbu -n name %1 -x ext %1
  70. (*) Works fine.
  71.  
  72.   -l  Parse disk drive letter only.    <sym> <filespec>
  73.       Sets symbol to the drive letter portion of arg1. The colon
  74.       drive/name separator is always removed.
  75.       ERRORLEVEL:  Length of resulting string.
  76.       Example:  tbu -d drive c:\tbu.exe  sets drive to c
  77.  
  78.   -c  Input character from keyboard.   <sym> [prompt] [valid] [secs]
  79.       Sets symbol to the upper case value of the character entered.
  80.       Optional prompt (may be ""). Optional valid characters, are
  81.       not case sensitive. Optional seconds for timed input. Accepts
  82.       printable keys only.
  83.       ERRORLEVEL:  ASCII code of character entered, 0 = timeout.
  84.       Example:  tbu -c ans "Ok (Y/N)?"  sets ans to any & prompts.
  85.       Example:  tbu -c ans "" yn        sets ans to Y or N.
  86.       Example:  tbu -c ans "" "" 20     sets ans to any & times 20 secs.
  87.  
  88. (*) It appears as if it's possible to use a  \  character to delimit
  89. (*) quote marks if you want them to be part of the prompt line. That
  90. (*) is, if you wanted your prompt line to read:
  91. (*)            What's your "handle" today?
  92. (*) *with* the quotes, you should make the instruction look something like:
  93. (*) tbu -c ans "What's your \"handle\" today? "
  94.  
  95. (*) If you use the -c operator and you have not specified a particular
  96. (*) string to be used for the response, and if you hit ENTER, it looks
  97. (*) as if a single space is entered into the variable you specify
  98. (*) in the command. In other words, it creates the variable and puts a
  99. (*) space - or maybe a NUL character, I dunno - into the variable.
  100.  
  101. (*) Note: if you use a time-delay and the program times out, you
  102. (*) get a moderately loud, shrill beep out of it. Just be warned,
  103. (*) it's not especially restful.
  104.  
  105.   -s  Input string from keyboard.      <sym> [prompt] [max length]
  106.       Sets symbol to the string entered. Optional prompt (may
  107.       be ""). Optional max input length (128 chars default).
  108.       ERRORLEVEL:  Length of string entered.
  109.       Example:  tbu -s user "Your name: "  sets user to string.
  110.  
  111. (*) In other words, the program sends the prompt:
  112. (*)                   Your name:
  113. (*) to the screen. Type something and hit ENTER. Then
  114. (*) an environment variable "USER" is written, containing
  115. (*) whatever you typed in response.
  116.  
  117. (*) In this case if you press ENTER in response to the prompt,
  118. (*) the program does NOT create a variable having the specified name.
  119.  
  120. (*) When using either the -s or -c options, you can include ANSI.SYS
  121. (*) cursor positioning commands in the prompt text. Using <esc> to mean
  122. (*) the <esc> character (alt 27), here's an example:
  123.  
  124. (*) tbu -s ans "<esc>[2J<esc>[14;8HThis is the prompt text: "
  125.  
  126. (*) Result: clears the screen and places the prompt line beginning
  127. (*) at row 14, column 8. ANSI.SYS text attribute commands can also
  128. (*) be placed into the prompt line this way.
  129.  
  130. (*) The "max length" function mentioned in the docs above does not
  131. (*) appear to work at all.
  132.  
  133. (*) Other undocumented features: if you use the -s switch and
  134. (*) create a prompt line, while entering text on the prompt line
  135. (*) you can use CTRL W to delete a word to the left of the cursor.
  136. (*) You can use CTRL U to clear the *entire* prompt line.
  137.  
  138.   -r  Get DOS revision.                <sym> [major|minor|both]
  139.       Sets symbol to the desired portion of the DOS version.
  140.       Default = Both.
  141.       ERRORLEVEL:  None.
  142.       Example:  tbu -r rev major
  143.  
  144.   -d  Get system date.                 <sym> <format>
  145.       Sets symbol to the system date in the specified format.
  146.       The format is embedded in a string:  $[modifier]<element type>
  147.       Element types:        Allowable modifiers:
  148.           y = year              [a for 2 digit year]
  149.           m = month             [0_wWaA]
  150.           d = day of month      [0_]
  151.           j = Julian date       [0_]
  152.           k = day of week       [0_wWaA] (numeric Sun=0, Mon=1,...)
  153.       Modifiers for numeric values:
  154.           0 = zero pad on left
  155.           _ = space pad on left
  156.       Modifiers for string values:
  157.           w = full word instead of number (W = all upper case)
  158.           a = abbreviated word instead of number (A = all upper case)
  159.       ERRORLEVEL:  None.
  160.       Example:  tbu -d date "The date is: $wk, $wm, $0d $y"
  161.  
  162. (*) The result of the example is an environment variable "DATE"
  163. (*) containing the string:
  164. (*)             The date is: Monday, March, 13 1989
  165. (*) Note that the omission of a comma in the above instruction leads
  166. (*) to no comma following the "13" in the environment variable itself.
  167. (*) Another example:
  168.  
  169. (*)                 tbu -d dt $0m-$d-$ay
  170. (*) This creates a variable "dt" containing something like
  171. (*) 02-13-89 if it were 13 February, 1989, or something like
  172. (*) 11-15-89 if it were 15 November, 1989.
  173.  
  174.   -t  Get system time.                 <sym> <format>
  175.       Sets symbol to the system time in the specified format.
  176.       The format is embedded in a string:  $[modifier]<element type>
  177.       Element types:        Allowable modifiers:
  178.           h = hours             [0_]
  179.           m = minutes
  180.           s = seconds
  181.           a = AM/PM             (h = 1-12 if present)
  182.           d = daylight          (Y = daylight s